Windows Phone 7 : User Interface - Using Panorama and Pivot Controls

1. Problem

You need to develop an application that shows a lot of information that is separated into categories or groups. You don't want to put this information on separate pages and provide a navigation system; you would prefer to have them on the same main page of the application.

2. Solution

You can use either a Panorama control or a Pivot control provided by the Microsoft.Phone.Controls assembly.

3. How It Works

Both controls are similar in their programming and final output, so you can choose which one to use in your application. Each provides a Title property used to specify a title for the application. Each also provides the xxxItem child control (where xxx can be either a Pivot or Panorama control) used to specify a category or a group of information. You can specify whatever you want within this child control because it derives from ContentControl. The common implementation provides a ListBox control with its own template providing an image and some related text.

In the Windows Phone 7 operating system, you can see the Panorama control in action, executing the Marketplace application. On the other hand, execute the Settings application to see the Pivot control in action. As you can see, the main difference between these two controls is the background image provided by the Panorama control. The Title property in the Panorama control uses a larger font respect to the one provided by the Pivot control. Indeed, with the Panorama control, the title gives the panorama effect, because the full title is readable only by scrolling between panorama's items.

4. The Code

In this recipe, you will create an application that shows today's BBC program schedule by using both a Panorama and a Pivot control. The TV schedule is provided by a web service from the www.bleb.org site .

The first operation to perform is to add a reference to the Microsoft.Phone.Controls.dll assembly, only if you haven't created the application from the Windows Phone Panorama Application or the Windows Phone Pivot Application Visual Studio 2010 template.

In this case, we started the TvSchedule7 application (and the TvSchedulePivot7 application too) from the Visual Studio 2010 template, so we already have all that is needed to use both Panorama and Pivot controls. This template implements the Model-View-ViewModel (MVVM) architecture, so you will find the ViewModels folder in the Visual Studio solution containing two files: ItemViewModel.cs and MainViewModel.cs. Thanks to this architecture, you can separate data into its visual representation.

In ItemViewModel.cs, you have to describe and define the item's characteristics. So you have to define properties representing your data. In this case, a TV program is defined by a title, a description, and the scheduled time. So you add three properties into the ItemViewModel.cs file:

public class ItemViewModel : INotifyPropertyChanged

{
        private string _title;
        /// <summary>
        /// Programme title
        /// </summary>
        /// <returns></returns>
        public string Title
        {
            get
            {
                return _title;
            }
            set
            {
                if (value != _title)
                {
                    _title = value;
                    NotifyPropertyChanged("Title");
                }
            }
        }

        private string _startEnd;
        /// <summary>
        /// Programme start end.
        /// </summary>
        /// <returns></returns>
        public string StartEnd
        {
            get
            {
                return _startEnd;
            }
            set
            {
                if (value != _startEnd)
                {
                    _startEnd = value;
                    NotifyPropertyChanged("StartEnd");
                }
            }
        }

					  

        /// <summary>
        /// Sample ViewModel property; this property is used in the view to display its
        /// value using a Binding.
        /// </summary>
        /// <returns></returns>
        public string Description
        {
            get
            {
                return _description;
            }
            set
            {
                if (value != _description)
                {
                    _description = value;
                    NotifyPropertyChanged("Description");
                }
            }
        }

        public event PropertyChangedEventHandler PropertyChanged;
        private void NotifyPropertyChanged(String propertyName)
        {
            PropertyChangedEventHandler handler = PropertyChanged;
            if (null != handler)
            {
                handler(this, new PropertyChangedEventArgs(propertyName));
            }
        }
    }

					  

public class MainViewModel : INotifyPropertyChanged
    {
        public MainViewModel()
        {
            this.BBC1Items = new ObservableCollection<ItemViewModel>();
            this.BBC2Items = new ObservableCollection<ItemViewModel>();
            this.ITV1Items = new ObservableCollection<ItemViewModel>();
        }

        /// A collection for ItemViewModel objects.
        /// </summary>
        public ObservableCollection<ItemViewModel> BBC1Items { get; private set; }
        public ObservableCollection<ItemViewModel> BBC2Items { get; private set; }
        public ObservableCollection<ItemViewModel> ITV1Items { get; private set; }
. . .

					  

Then in the LoadData method, you define the code to load the TV schedule from the web service. So you create a new WebClient object and hook its own DownloadStringCompleted event. This is raised when the call to the DownloadStringAsync method is completed. You call this method to retrieve information from the web service. The last method parameter represents a user token string that is passed as a parameter to the DownloadStringCompleted event handler. You use it to determine which TV channel is required for the web service and which is the next channel to retrieve.

public void LoadData()
{
    web = new WebClient();

    web.DownloadStringAsync(new Uri("http://www.bleb.org/tv/data/listings/0/bbc1.xml"),
                            "BBC1");
    web.DownloadStringCompleted +=
                  new DownloadStringCompletedEventHandler(web_DownloadStringCompleted);
}

					  

The real data loading is in the DownloadStringCompleted event handler. Because the web service returns XML content, you use the LINQ to XML library to load and manage this result. A snippet of the XML content is shown here:

<?xml version="1.0" encoding="UTF-8"?>
<!-- produced for the bleb.org TV system at Sun Mar  6 08:39:03 2011 -->
<channel id="bbc1" source="XMLTV" date="06/03/2011">
  <programme>
    <flags>(S)</flags>
    <desc>The latest news, sports, business and weather from the BBC's Breakfast
          team.</desc>
    <title>Breakfast</title>
    <end>0735</end>
    <start>0600</start>
    </programme>
. . .

					  

Finally, you set the IsDataLoaded property to true to indicate that the loading operations are concluded:

void web_DownloadStringCompleted(object sender, DownloadStringCompletedEventArgs e)
        {
            if (e.Error != null && e.Error.Message != string.Empty)
                return;

            if (e.Cancelled)
                return;

            string result = e.Result;
            XElement xml = XElement.Parse(result);

            if (xml != null)
            {
                foreach (XElement programme in xml.Descendants("programme"))
                {
                    ItemViewModel item = new ItemViewModel();
                    item.Description = programme.Element("desc").Value;
                    item.Title = programme.Element("title").Value;
                    item.StartEnd = programme.Element("start").Value + " - " +
                                    programme.Element("end").Value;

                    switch ((string)e.UserState)
                    {
                        case "BBC1":
                            this.BBC1Items.Add(item);
                            break;
                        case "BBC2":
                            this.BBC2Items.Add(item);
                            break;
                        case "ITV1":
                            this.ITV1Items.Add(item);
                            break;
                    }
                }
            }

            switch ((string)e.UserState)
            {
                case "BBC1":
                    web.DownloadStringAsync(
                        new Uri("http://www.bleb.org/tv/data/listings/0/bbc2.xml"), "BBC2");
                    break;
                case "BBC2":
                    web.DownloadStringAsync(
                        new Uri("http://www.bleb.org/tv/data/listings/0/itv1.xml"), "ITV1");
                    break;
            }

            this.IsDataLoaded = true;
        }

					  

Both the Panorama and Pivot item children controls have defined a ListBox with a template including an image control, and two TextBlocks within a stack panel. The ListBox—as with most of the controls—provides the binding feature used to populate the control reading data from a data source. The ItemsSource attribute from the ListBox control accepts the binding to the collections defined in the MainViewModel properties such as BBC1Items, BBC2Items, and ITV1Items. The binding mechanism is pretty smart to add a ListBox item for each related item in the collection. We don't need to write any code lines. By always using the binding feature, you can specify which ItemViewModel property to use to print the text blocks' text:

. . .
<ListBox Margin="0,0,-12,0" ItemsSource="{Binding BBC1Items}"
    SelectionChanged="lb_SelectionChanged" x:Name="lbBBC1">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Margin="0,0,0,17">
            <Image Source="images/bbc1.jpg" Height="100" Width="100" />
            <StackPanel Width="311">
                <TextBlock Text="{Binding Title}" TextWrapping="Wrap"
                           Style="{StaticResource PhoneTextExtraLargeStyle}"/>
                <TextBlock Text="{Binding StartEnd}" TextWrapping="Wrap"
                           Margin="12,-6,12,0"
                           Style="{StaticResource PhoneTextSubtleStyle}"/>
            </StackPanel>
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>
. . .

					  

Now let's see the differences in the XAML code in order to define either a Panorama or a Pivot control. The Panorama has a background that is not provided by the Pivot, but the rest of code is really similar.

Here is the Pivot control definition with one item:

. . .
    <!--LayoutRoot is the root grid where all page content is placed-->

<Grid x:Name="LayoutRoot" Background="Transparent">
        <!--Pivot Control-->
        <controls:Pivot Title="TvSchedule7">
            <!--Pivot item one-->
            <controls:PivotItem Header="BBC1">
                <!--Double line list with text wrapping-->
. . .

And here is the Panorama definition:

. . .
    <!--LayoutRoot is the root grid where all page content is placed-->
    <Grid x:Name="LayoutRoot" Background="Transparent">

        <!--Panorama control-->
        <controls:Panorama Title="TvSchedule7">
            <controls:Panorama.Background>
                <ImageBrush ImageSource="PanoramaBackground.jpg"/>
            </controls:Panorama.Background>

            <!--Panorama item one-->
            <controls:PanoramaItem Header="BBC1">
. . .

That's it. The code defines the other two control items with the other two TV channels, but the code is pretty much the same (it differs only in its ID and header text).

5. Usage

We have two projects: TvSchedule7 that uses the Panorama control, and TvSchedulePivot7 that uses the Pivot control. So open two Visual Studio 2010 program instances and load these two projects. Press Ctrl+F5 from one Visual Studio 2010 instance and wait until the application is deployed and started. For example, starting with the TvSchedule7 example, you will see the Panorama control showing a background with BBC1 TV scheduled programs and part of BBC2 TV scheduled programs (see the left part of Figure 1). You can flick to the left so that the Panorama control shows some other part of the title and the BBC2's program schedules. When you reach the last item of the Panorama control and flick again to the left, the control will show you the first page.

Leaving the emulator in execution, launch the other project. The Pivot control will briefly show the same information but with a different user interface (see the right-hand side of Figure 1). The title is fully readable, and there are more list box items visible. Even with the Pivot control, you can flick either left or right to navigate through items.

Figure 1. Panorama vs Pivot controls